Webhooks Overview

Webhooks allow you to receive real-time HTTP notifications when events occur on Safe Smart Accounts. Instead of polling the API for changes, your application receives push notifications as events happen, enabling efficient, event-driven architectures.

How webhooks work

1. Subscribe: Configure a webhook endpoint URL in the developer dashboard ↗ (opens in a new tab).
2. Receive: When a relevant event occurs (for example, a transaction is proposed, confirmed, or executed), Safe Infrastructure sends an HTTP POST request to your endpoint with event details in the JSON body.
3. Process: Your server processes the event and responds with a 200 OK status to acknowledge receipt.

Availability

Webhook deliveries do not count as API units

Webhook deliveries are not counted toward your monthly API unit quota. Only HTTP requests you make to the API consume API units.

1 API unit = 1 HTTP request. Webhook deliveries are excluded.

Consider using webhooks to reduce your API usage if you're currently polling for updates.

Supported event types

Event type	Description
NEW_CONFIRMATION	A new signature was added to a pending transaction.
EXECUTED_MULTISIG_TRANSACTION	A multisig transaction was executed on-chain.
PENDING_MULTISIG_TRANSACTION	A new multisig transaction was proposed.
DELETED_MULTISIG_TRANSACTION	A pending multisig transaction was deleted.
INCOMING_TOKEN	An ERC-20 token transfer was received.
INCOMING_ETHER	A native token (ETH) transfer was received.
OUTGOING_TOKEN	An ERC-20 token transfer was sent.
OUTGOING_ETHER	A native token (ETH) transfer was sent.
MODULE_TRANSACTION	A transaction was executed via a module.
MESSAGE_CREATED	A new off-chain message was created.
MESSAGE_CONFIRMATION	A confirmation was added to an off-chain message.
SAFE_CREATED	A new Safe was created.
REORG_DETECTED	A blockchain reorganization was detected.
NEW_DELEGATE	A new delegate was added.
UPDATED_DELEGATE	An existing delegate was updated.
DELETED_DELEGATE	A delegate was removed.

Retry semantics

If your endpoint doesn't respond with a 2xx status code within the request timeout, Safe Infrastructure retries delivery:

• Timeout: 5 seconds per request.
• Retries: Up to 2 retries on transient network errors and 5xx responses.
• Back-off: Exponential, starting at 200 ms with a 2× factor (200 ms, then 400 ms).

4xx responses are not retried. Return a 4xx if you want to drop the delivery permanently, for example if the endpoint has been intentionally removed.

Idempotency

Every webhook delivery carries an X-Delivery-Id header, a stable UUID that stays the same across retries of the same event. Use it to deduplicate events on your side:

If you receive two requests with the same X-Delivery-Id, treat them as the same event. This guarantees you process each event exactly once, even if the network is flaky and a delivery gets retried.

Security

We recommend configuring an Authorization header on your webhook endpoint so that only authenticated requests from Safe Infrastructure are accepted. You can set this up in the developer dashboard when creating your webhook. This prevents malicious actors from posting fake events to your service.

Important notes

• Webhook payloads are intentionally minimal. They serve as signals to notify your application that something changed. Use the API to fetch full details after receiving an event.
• Safe Infrastructure sends notifications for blockchain reorgs. Always verify event data against the API to ensure consistency.

Next steps

• Setup & Configuration: Configure your webhook endpoints.
• Quotas & Limits: Understand how webhook deliveries affect your quota.